src/utils/documents.server.ts (1)

630-636: Consider extending error handling to recursive directory fetches.

The enhanced error handling added for the initial fetch (lines 561-601) isn't applied to the recursive fetch within buildFileTree. If a subdirectory request hits a 403 or 429, it will silently produce a confusing warning about "Expected an array" rather than providing the detailed rate-limit diagnostics.

This is pre-existing behavior and outside the scope of this PR, but could be addressed in a follow-up if nested fetches frequently fail.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/utils/documents.server.ts` around lines 630 - 636, The recursive
directory fetch inside buildFileTree (the fetch to file._links.self using
fetchOptions that assigns directoryFilesResponse/directoryFiles) lacks the
robust error handling used for the initial fetch; update this block to mirror
that logic: check directoryFilesResponse.ok and if false read response.text() /
json() to include the error body in processLogger.warn/error, detect 403/429 and
surface rate-limit headers (x-ratelimit-limit, x-ratelimit-remaining,
x-ratelimit-reset) in the log, and throw or return a clear error instead of
allowing a misleading "Expected an array" warning so callers get the same
diagnostic detail as the top-level fetch.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

src/utils/documents.server.ts (2)

546-555: Extract the placeholder sentinel to a shared constant.

The string 'USE_A_REAL_KEY_IN_PRODUCTION' is hardcoded here and in src/utils/env.functions.ts (line 26). If one changes without the other, unauthenticated requests would resume silently—and staleOnError would mask the resulting failures.

♻️ Suggested refactor

Create a shared constant:

// src/utils/constants.ts (or similar)
export const GITHUB_TOKEN_PLACEHOLDER = 'USE_A_REAL_KEY_IN_PRODUCTION'

Then use it in both locations:

+import { GITHUB_TOKEN_PLACEHOLDER } from './constants'
+
 const githubToken = env.GITHUB_AUTH_TOKEN
 const hasConfiguredGitHubToken =
-  Boolean(githubToken) && githubToken !== 'USE_A_REAL_KEY_IN_PRODUCTION'
+  Boolean(githubToken) && githubToken !== GITHUB_TOKEN_PLACEHOLDER

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/utils/documents.server.ts` around lines 546 - 555, Extract the literal
sentinel 'USE_A_REAL_KEY_IN_PRODUCTION' into a shared exported constant (e.g.
GITHUB_TOKEN_PLACEHOLDER) and replace all occurrences with that constant so both
modules use the same source of truth; specifically add the constant to a
new/shared module (e.g. constants.ts) and update the usages in
src/utils/documents.server.ts (symbols: githubToken, hasConfiguredGitHubToken,
fetchOptions) and src/utils/env.functions.ts to import and compare against
GITHUB_TOKEN_PLACEHOLDER instead of the hardcoded string.

---

290-290: Enabling staleOnError provides resilience but may mask configuration issues.

Per context snippet 1, the stale cache has no TTL and catches all errors—including 401/403 from a misconfigured GITHUB_AUTH_TOKEN. This means broken auth could serve indefinitely stale docs without surfacing the root cause until the 300-item LRU evicts entries.

Consider adding monitoring/alerting on repeated stale-cache hits or auth failures so misconfigurations don't go unnoticed.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/utils/documents.server.ts` at line 290, The config sets staleOnError:
true which can mask auth/config issues; update the code that constructs the
cache/fetcher (the place using staleOnError) to emit telemetry and logs whenever
a stale-cache hit occurs or an upstream fetch fails (especially on 401/403
related to GITHUB_AUTH_TOKEN), e.g. increment a metric and log a warning with
the failure status and token-related context, and add a simple alert rule (high
rate of stale hits or repeated 401/403) so operators are notified when stale
responses are being served.

src/routes/$libraryId/$version.docs.framework.$framework.examples.$.tsx (1)

80-80: Minor naming inconsistency: variable name suggests filename but receives full path.

The variable explorerCandidateStartingFileName now receives fallbackPath, which is a full path (e.g., src/main.tsx), not just a filename. The code works correctly since determineStartingFilePath compares against full paths, but the naming could be clearer.

Suggested rename for clarity

-      const explorerCandidateStartingFileName = fallbackPath
+      const explorerCandidateStartingPath = fallbackPath

And update the reference on line 86 accordingly.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/routes/`$libraryId/$version.docs.framework.$framework.examples.$.tsx at
line 80, The variable explorerCandidateStartingFileName is misnamed because it
holds a full path (fallbackPath); rename it to explorerCandidateStartingFilePath
and update all references (including the call to determineStartingFilePath) so
names reflect that it contains a path rather than just a filename.